home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE2 / PD / VINCE / !ViNCe / DeepKeys / DeepK_Help < prev    next >
Text File  |  2002-07-06  |  4KB  |  99 lines
  1.  DeepKeys 2.02 (23-Sep-2000) © Cerilica 2000
  2.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4.  DeepKeys has two functions, it implements a word-deep rather than byte-deep
  5.  keyboard buffer, and it extends the Wimp KeyPress message with modifiers and
  6.  physical key number.
  7.  
  8.  DeepKeys can be distributed with any program, PD or commercial, providing that
  9.  this documentation is included intact, and that the following credit is
  10.  reproduced in any other documentation, manuals and/or help files:
  11.  
  12.     DeepKeys © Cerilica Ltd 2000  Contact: <simon@cerilica.com>
  13.  
  14.  
  15.  Keyboard Buffer
  16.  ~~~~~~~~~~~~~~~
  17.  DeepKeys implements a word-sized keyboard buffer. Consequently all system
  18.  calls that deal with the keyboard buffer now input and output word-sized
  19.  values. "Deep" key ranges are allocated by Alan Glover at Pineapple Software
  20.  <allocate@pinesoft.demon.co.uk>.
  21.  
  22.  InsV, RemV and CnpV handle word-sized keypress codes, but block mode is still
  23.  byte-orientated. OS_Byte 138,0,<code> can take "deep" key codes, and OS_ReadC
  24.  returns word-sized values.
  25.  
  26.  
  27.  KeyPress Poll Event
  28.  ~~~~~~~~~~~~~~~~~~~
  29.  DeepKeys installs a wimp filter which extends the normal keypress event. Poll
  30.  reason 8 returns a word-sized keypress code at block+24 as normal, but this
  31.  followed by a new information word at block+28 containing the state of the
  32.  modifier keys at the time the keypress was detected, and the physical key
  33.  number of the non-modifier key generating the keypress:
  34.  
  35.   +24 KeyPress code (word)
  36.   +28 DeepKey information:
  37.       b0 Left Shift    b1 Right Shift
  38.       b2 Left Ctrl     b3 Right Ctrl
  39.       b4 Left Alt      b5 Right Alt
  40.       b6 Left Logo     b7 Right Logo
  41.       b8 Menu key
  42.       b9-14 reserved (0)
  43.       b15 Always 0
  44.       b16-31 Physical key number
  45.  
  46.  If an application requires DeepKeys, it should RMEnsure it. DeepKeys has been
  47.  allocated the common installation point of "<Boot$ToBeLoaded>.!!DeepKeys"
  48.  (note double pling), or it can be included within the application.
  49.  
  50.  If an application wants to make use of DeepKeys if available, but does not
  51.  require it, DeepKey's presence can be detected by setting bit 15 of block+28
  52.  before calling Wimp_Poll or Wimp_PollIdle - this bit is guaranteed to be clear
  53.  if the DeepKeys information word is present.
  54.  
  55.  Most keyboards generate key codes for the Logo and Menu keys (Cerilica's MMK
  56.  certainly does), but DeepKeys also treats them as modifiers, so an individual
  57.  application can use combinations such as Logo-A just as if it were Ctrl-A.
  58.  When operating like this, the code generated by the initial Logo or Menu
  59.  keypress must be ignored (but not passed on).
  60.  
  61.  The physical key number can be used to assign different actions to sets of
  62.  keys that generate the same keypress code - Return and Enter for example.
  63.  When implementing such a scheme, make sure that the DEFAULT action is that
  64.  assigned to the more-common keypress, eg:
  65.  
  66.    CASE block!24 OF
  67.      WHEN 13:REM Return, Enter or Ctrl-M
  68.        CASE (block!28)>>>16 OF
  69.          WHEN &67: PROCkeypress_ENTER
  70.          WHEN &54: PROCkeypress_CTRL_M
  71.          OTHERWISE:PROCkeypress_RETURN
  72.        ENCASE
  73.  
  74.  This ensures sensible operation with future keyboards, and with keypresses
  75.  not generated by the keyboard - see following section.
  76.  
  77.  
  78.  Problems
  79.  ~~~~~~~~
  80.  RemV block mode cannot sensibly be used - word values in the buffer will be
  81.  truncated to their lowest eight bits.
  82.  
  83.  Key codes inserted into the buffer by software, rather than by the keyboard,
  84.  do not have modifier or physical keys associated with them. When delivered
  85.  to a Wimp program it will report the state of the keyboard modifiers at the
  86.  time of the simulated keypress, and the physical key number of the last real
  87.  keypress. This physical key number will NOT match the key code inserted. This
  88.  is why Wimp applications must be careful about interpreting the physical key
  89.  number, as described above.
  90.  
  91.  Version 2.02 of the DeepKeys module does not pass keyboard buffer events on
  92.  to existing claimants of the InsV, RemV and CnpV vectors, and so must be
  93.  loaded first to avoid disabling some utilities - hence the allocated
  94.  install position "<Boot$ToBeLoaded>.!!DeepKeys". Later versions solve this.
  95.  
  96.  
  97.  DeepKeys is copyright Cerilica Limited and was written by Simon Birtwistle.
  98.  <http://www.cerilica.com/>                      <mailto:simon@cerilica.com>
  99.